
//
// Copyright 2009 Arne Halvorsen (arne.halvorsen@gmail.com)
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

// Project page: http://code.google.com/p/mf4jexamples/

//
// 091119 - aha42 - Created.
// 091121a- aha42 - License, java doc and in line sample code doc.
// 091121b- aha42 - Added project page (google code) to header comment above.
// 091121c- aha42 - Main method java doc and improved in line sample code doc.
// 091121d- aha42 - In line example code doc fix.
// 091122a- aha42 - Minor improvement to output print.
// 091122b- aha42 - Very minor in line doc fix.
//

package org.aha.mf4j.examples;

import java.io.IOException;

import org.aha.mf4j.FlickrSession;
import org.aha.mf4j.response.FlickrObject;
import org.aha.mf4j.util.CommandLineParser;

/**
 * <p>
 *   Sample code showing doing an authenticated call.
 * </p>
 * @author Arne Halvorsen (aha42)
 */
public final class Authentication 
{
  private Authentication(){} // Pure main method class, never instantiated.
  
  /**
   * <p>
   *   Runs sample code.
   * </p>
   * <table border='1'>
   *   <tr><th>Option</th><th>Description</th><th>Mandatory</th></tr>
   *   <tr>
   *     <td>{@code -key <app_key>}</td>
   *     <td>Flickr application key.</td>
   *     <td>Yes.</td>
   *   </tr>
   *   <tr>
   *     <td>{@code -secret <secret>}</td>
   *     <td>Secret shared between application and Flickr.</td>
   *     <td>
   *       Yes, is needed for authentication and sample code do an 
   *       authenticated Flickr method call.
   *     </td>
   *   </tr>   
   * </table>
   * @param args Command line arguments, see above table for accepted options.
   */
  public static void main(String[] args) 
  {
    try
    {
      CommandLineParser clp=new CommandLineParser(args);
      
      String apiKey=clp.mandatoryValue("-key");
      String secret=clp.mandatoryValue("-secret");
      
      // EXAMPLE CODE STARTS.
      
      // The constructor call to make a FlickrSession is the one that takes 
      // two parameters: besides the always needed application key the shared
      // secret between application and Flickr must be known and is passed as 
      // second argument here.
      FlickrSession session=new FlickrSession(apiKey, secret);
      
      // Application is not yet authenticated, that is done with the
      // FlickrSession.authenticate call below.
      
      // Authenticate with 'write' permission, valid arguments to this call is
      // 'read', 'write' and 'delete'. Note that 'read' is default value.
      //
      // Exactly how authentication details are presented to end user is 
      // delegated to an object of type
      // org.aha.mf4j.Authenticator that can be registered using the method
      // FlickrSession.setAuthenticator.
      //
      // If client has not registered any Authenticator an instance of
      // org.aha.mf4j.SimpleAuthenticator is used (will be used in this 
      // example).
      //
      // SimpleAuthenticator simply writes to standard out URL to flickr page 
      // end user must visit (requires user to log in) in order to authenticate
      // and wait for end user to simply hit return to indicate done so.
      //
      // This is actually to much privileges for call we do later...
      if (session.authenticate("write")) 
      {
        // When we have authenticated then we can get a FlickrObject that has 
        // been parsed from the Flickr method flickr.auth.getToken, we can get
        // user id (nsid), user name and possible full name from this of 
        // authenticated end user.
        FlickrObject user=session.getUser();
        System.out.println("nsid : "+user.getMandatoryAttribute("nsid"));
        System.out.println("user name : "+
          user.getMandatoryAttribute("username"));
        if (user.hasAttribute("fullname")) 
          System.out.println("full name : "+user.getAttribute("fullname"));
        else
          System.out.println("full name not given");
        System.out.println();
      
        // When authenticated we can make an authenticated call, make the same 
        // as in Flickr's API doc example found here: 
        // http://www.flickr.com/services/api/auth.howto.desktop.html
        FlickrObject resFo=session.createRequest("flickr.blogs.getList")
          .perform();
      
        // Prints parsed result from authenticated call.
        resFo.printHierarchy();
      }
      else
      {
        // That Flickr.authenticate return false tells that end user has told
        // that choose not to authenticate.
        System.out.println("User choose not to authenticate");
      }
      
      // EXAMPLE CODE ENDS.
      
      System.exit(0);
    }
    catch (IOException iox)
    {
      iox.printStackTrace();
      System.exit(-1);
    }
  }
  
}
